<?php
/**
 * Abstract class for plugins type of <i>Psa_Plugin_Router</i>.
 * 
 * LICENSE:
 * 
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
 * 
 * You should have received a copy of the GNU Lesser General Public License
 * along with This library. If not, see <{@link http://www.gnu.org/licenses/}>.
 *
 * @link http://code.google.com/p/phpstartapp/
 * @author Bojan Mauser <bmauser@gmail.com>
 * @copyright Bojan Mauser 2009
 * @package psa
 * @subpackage plugins
 * @version $Id: Psa_Plugin_Router.class.php 116 2008-09-17 23:39:58Z bmauser $
 */


/**
 * Abstract class for plugins type of <i>Psa_Plugin_Router</i>.
 * Router plugins is called by {@link front_controller.php} script so it is
 * firstly called before all other plugins. Router plugin is used to decide which controller to call.
 * That decision can be made from given URL path if your web server is set to use rewrite rules,
 * which is common practice, but can also be made from get or post values. It's up to you what you will use.
 *
 * If you want to use rewrite rules you must set up your web server for this, with Apache web server 
 * you can do it by enabling {@link http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html mod_rewrite} 
 * by adding line like this into the configuration file:
 * 
 * <kbd>LoadModule rewrite_module modules/mod_rewrite.so</kbd>
 * 
 * Make sure that you can override (AllowOverride directive) rewrite settings with .htaccess file.
 * Edit .htaccess file to match your configuration.
 * 
 * There cannot be more than one Router plugin in your application.
 * 
 * You can write <i>Psa_Plugin_Router</i> plugins by extending this class. Here is an example:
 * 
 * <code>
 * <?php
 * class Router extends Psa_Plugin_Router{
 * 	
 * 	// you have to define psa_main() method in your child class
 * 	function psa_main(){
 *		
 * 		// global config array from config.php file
 * 		global $PSA_CFG;
 * 		
 * 		// remove query string from url
 * 		$request_uri_arr = explode('?',$_SERVER["REQUEST_URI"]);
 * 		
 *		// If application root folder is in subfolder from server root like: www.example.com/my/application/
 *		// remove unnecessary part of path. In case of url above that would be '/my/application'.
 *		// This value should be set in $PSA_CFG['folders']['basedir_web'] config variable in psa config.php file
 *		// or even better in site specific config_override.php file.	
 *		if($PSA_CFG['folders']['basedir_web'])	
 *			$request_uri_arr[0] = str_replace($PSA_CFG['folders']['basedir_web'] . '/', '', $request_uri_arr[0]);
 *		else
 *			// remove first '/' if application is in the web server root folder
 *			$request_uri_arr[0] = substr($request_uri_arr[0], 1);
 * 		
 * 		// explode REQUEST_URI and find controller name
 * 		$request_uri_arr = explode('/',$request_uri_arr[0]);
 * 		
 * 		// This router is written to find controller name from url path and that name should be
 * 		// the the first element of $request_uri_arr array.
 * 		// For simple applications you will know the name of your controller class so you don't
 * 		// need to do this.
 * 
 * 		// controller name should be the first element of the array
 * 		$controller_alias = $request_uri_arr[0];
 * 
 * 		// You can check here if controller with this name is registered and if not call default Web_Controller.
 * 		// But in this example I know that may application has only two controllers: Web_Controller and
 * 		// Soap_Controller. If url starts with webservice/ Soap_Controller should be called, otherwise 
 * 		// call Web_Controller.
 * 
 * 		// if Soap_Controller should be called
 * 		if($controller_alias == 'webservice'){
 * 				
 * 			// load data about plugins
 * 			Psa_Plugin::get_instance()->set_data();
 * 			
 * 			// set controller name
 * 			$controller_name = 'Soap_Controller';
 * 			
 * 			// In this case the action name is second element of $request_uri_arr array so we want to strip
 * 			// the first element (controller name/alias) from array because this array will be passed to 
 * 			// controller's psa_main() method. That way you know that the first element is always action name.
 * 			$request_uri_arr = array_slice($request_uri_arr, 1);
 * 		}
 * 		// default controller is Web_Controller
 * 		else{
 * 			$controller_name = 'Web_Controller';
 * 				
 * 			// start session
 * 			session_start();
 * 				
 * 			// restore plugin object from session
 * 			Psa_Plugin::get_instance()->session_restore();
 * 		}
 * 
 * 		
 * 		// We want to call psa_main() method of the controller and pass $request_uri_arr to the controller 
 * 		// cause the same array will be needed there to decide which actions (models and views) to call.
 * 		$run_plugins[$controller_name]['psa_main'] = array($request_uri_arr);
 * 		
 * 		// call controller
 * 		psa_run_plugins($run_plugins);
 * 	}
 * }
 * ?>
 * </code>
 * 
 * <b>Note:</b> Router plugin class has to be named Router and file has to be named Router.php and placed 
 * in first directory with plugins (by settings in {@link config.php}). That limitation exists only for router plugin.
 * 
 * @see Psa_Plugin_Controller
 */
abstract class Psa_Plugin_Router{
	
	
	/**
	 * Method that must be defined by the child class.
	 * It is supposed to add main functionality of the router plugin into this method.
	 */	
	abstract protected function psa_main();
}
